home *** CD-ROM | disk | FTP | other *** search
/ PD ROM 1 / PD ROM Volume I - Macintosh Software from BMUG (1988).iso / Programming / Complete Applications / Telecom / MacbinaryProtocol
Encoding:
Text File  |  1987-06-01  |  12.1 KB  |  203 lines  |  [TEXT/ttxt]
  1.  
  2.  
  3. Macintosh Binary Transfer Format ("MacBinary") Standard Proposal
  4. ----------------------------------------------------------------
  5. Dennis F. Brothers - 13 March 1985
  6. (Revision 1 - 10 April 1985 - Miscellaneous clarifications)
  7. (Revision 2 - 12 April 1985 - Corrected reversal of icon position v,h)
  8. (Revision 3 -  6 May   1985 - Added processor ID, general cleanup)
  9.   
  10. The following notes are a proposal for a standard format for binary transfer
  11. of arbitrary Macintosh documents via a telecommunication link. It is intended
  12. for use both between Macintoshes running (possibly different) terminal
  13. programs which adhere to the standard, and for use in uploading arbitrary
  14. Macintosh documents to remote systems (where it is presumed that they will be
  15. stored as an exact image of the data transmitted). A proposal is also made for
  16. standard processing to be performed on text files transferred via a protocol,
  17. to maximize the likelihood that text files transmitted to a remote system will
  18. be usable by that system, and that text files received from a remote system
  19. will be usable by the Macintosh.
  20. It is recommended that the format and procedures described here be referred
  21. to as "MacBinary", and that any terminal program implementing this format
  22. and procedures be called "MacBinary-Compatible".
  23. The binary format described is independent of the communication protocol used
  24. to accomplish the transfer, and assumes only that an 8-bit transparent
  25. transfer can be accomplished. Such protocols as Christensen (usually referred
  26. to as XMODEM or MODEM7), Kermit, and CompuServe A or B meet this requirement.
  27. Because of the proposed standard's MacTerminal/XMODEM heritage, there is a
  28. requirement that the transmitted data be padded (with nulls) to a 128-byte
  29. boundary at certain points, but this in no way implies that a block-oriented
  30. protocol must be used. The basic format proposed is identical to that used by
  31. MacTerminal, by Mike Boich and Martin Haeberli, and can be used with a version
  32. of MacTerminal that has had a patch applied to "normalize" its implementation
  33. of the XMODEM protocol. 
  34. In brief, the binary format consists of a 128-byte header containing all the
  35. information necessary to reproduce the document's directory entry on the
  36. receiving Macintosh; followed by the document's Data Fork (if it has one),
  37. padded with nulls to a multiple of 128 bytes (if necessary); followed by the
  38. document's Resource Fork (again, padded if necessary). The lengths of these
  39. forks (either or both of which may be zero) are contained in the header. 
  40. The format of the 128-byte header is as follows (offsets and lengths are given
  41. in decimal):  
  42.         Offset   Length   Contents
  43.         ------   ------   --------
  44.         000      1        Zero. This is a "version" byte.
  45.         001      1        Length of filename.
  46.         002      63       Filename (only "length" bytes are significant).
  47.        (the following 16 bytes are a standard Finder Info record)
  48.         065      4        File type.
  49.         069      4        File creator.
  50.         073      1        Finder flags:
  51.                                  Bit 7 - Locked.
  52.                                  Bit 6 - Invisible.
  53.                                  Bit 5 - Bundle.
  54.                                  Bit 4 - System.
  55.                                  Bit 3 - Bozo.
  56.                                  Bit 2 - Busy.
  57.                                  Bit 1 - Changed.
  58.                                  Bit 0 - Inited.
  59.         074      1        Zero.
  60.         075      2        File's vertical position within its window.
  61.         077      2        File's horizontal position within its window.
  62.         079      2        File's window or folder ID.
  63.        (End of Finder Info)
  64.         081      1        "Protected" flag (in low order bit).
  65.         082      1        Zero.
  66.         083      4        Data Fork length (bytes, zero if no Data Fork).
  67.         087      4        Resource Fork lenth (bytes, zero if no R.F.).
  68.         091      4        File's creation date.
  69.         095      4        File's "last modified" date.
  70.         099      27       Zero fill (reserved for expansion of standard).
  71.         126      2        Reserved for computer type and OS ID
  72.                           (this field will be zero for the current Macintosh).
  73. Note that it is the responsibility of the receiving terminal program to
  74. resolve file name conflicts, generally by somehow modifying the name of
  75. received file if there already exists a file with the original name on the
  76. target volume.
  77. Note also that, while the original window or folder ID and position may be
  78. transmitted, the receiving terminal program would not normally set these items
  79. for the received file, but would instead accept the values that the File
  80. Manager assigns when it creates the new file.
  81. It is suggested that Macintosh terminal programs implement two modes of
  82. protocol transfer: text and document. Text mode is used for unformatted files
  83. of type TEXT (with only a data fork), and document mode (using the binary
  84. format proposed here) is used for all other files. Document mode may also be
  85. used on text files, of course, if it is desired to preserve such things as the
  86. file's creator ID or creation date.
  87. The intent of text mode is to provide compatibility with text files on other
  88. systems. Toward that end, it is recommended that a linefeed be inserted after
  89. each return character as the text file is transmitted, and that, in the case
  90. of block-oriented protocols, the last block be explicitely padded with nulls
  91. if the text does not end on a block boundary. When receiving in text mode,
  92. linefeeds and trailing nulls should be stripped. If a CTRL-Z (Hex 1A) character
  93. is received following all other text (and before any null padding), it should
  94. also be stripped (Ctrl-Z is a common text terminator on CP/M and smoe other
  95. systems). Note that the above discussion applies only to text files transferred
  96. under some protocol, where an exact image of the transmitted data will be
  97. stored in a file on the remote system.
  98. When receiving a file via a protocol, a terminal program may distinguish
  99. between text and document modes by examining bytes 0, 74, and 82 of the first
  100. 128 bytes received. If they are each zero (and at least 128 bytes have been
  101. received), then it is a safe assumption that a MacBinary-formatted document
  102. is being received. Terminal programs implementing possible future versions of
  103. the proposed standard would, of course, accept an appropriate set of version
  104. numbers in byte 0. Note also that compatible extensions of Version 0 of the
  105. proposed standard are possible (one such is suggested below) that involve
  106. transmission of additional information following the information described here.
  107. For this reason, a terminal program should be implemented so as to perform
  108. the proper receive procedures for all data sent to it, but to ignore any data
  109. that it does not know what to do with.
  110. Since a text-mode document does not contain a file name, it is suggested that
  111. when text-mode is detected, a file be opened under a dummy name on the
  112. receiving Macintosh, the text written to that file, and the file renamed to a
  113. name selected by the user (via an SFPutFile box) after the reception is
  114. completed. This will avoid problems caused by indeterminate delays for name
  115. selection at the beginning of the file transfer.
  116. It is desirable to allow the user to specify the destination volume in advance
  117. of the actual start of transfer for either type of transfer. Two methods are
  118. suggested for this: provide a "Select Destination Volume" menu selection,
  119. presumably in the menu containing the "Receive File" selection; or query the
  120. user immediately after the "Receive File" menu selection is made. Either or
  121. both of these methods could be implemented in a given terminal program - the
  122. independent "Select Receive Volume" method is particularly desirable if the
  123. ESC-a/ESC-b automatic receive facility (see below) is implemented. The volume
  124. selection procedure should provide the same functions as the volume selection
  125. portion of the SFGetFile and SFPutFile dialog boxes.
  126. First proposed extension to the proposed standard:
  127. --------------------------------------------------
  128. It is proposed that the binary format described above be extended to allow the
  129. transmission of descriptive text with a Macintosh document (specifically, the
  130. descriptive text from the Finder's "Get Info" box for the file being
  131. transferred). This is to be accomplished in a transparent manner by assigning
  132. bytes 99 and 100 of the header described above to be used to hold the length
  133. of the descriptive text (or zero, if there is none). The descriptive text, if
  134. any, will begin on the 128-boundary immediately following the Resource Fork,
  135. if present, else the Data Fork, if present, else immediately following the
  136. header if neither fork is present. It is hoped that methods for reading and
  137. setting a file's "Get Info" text will be made public at some point.
  138. Notes on MacTerminal's XMODEM implementation, and a proposed extension:
  139. -----------------------------------------------------------------------
  140. Familiarity with the Christensen (XMODEM) protocol is assumed in the following
  141. discussion.
  142. When doing "Mac-to-Mac" transfers, using the binary format described above,
  143. unmodified MacTerminal does not use a true XMODEM protocol, and is therefore
  144. incompatible with most non-Mac systems. The differences lie in two specifics:
  145. the transmitting Macintosh initiates the transfer by sending the the two
  146. characters ESCAPE (hex 1B) and "a" (hex 61); the receiving Macintosh is
  147. expected to reply with the character ACK (hex 06). The transfer then proceeds
  148. using normal XMODEM procedures, except that each of the header and the two
  149. forks (if present) is treated as a separate XMODEM transfer, with the
  150. transmitting Macintosh waiting for a NAK (hex 15), then sending the blocks of
  151. that phase (beginning with a block number of one), then sending EOT (hex 04)
  152. and waiting for an ACK (hex 06) from the receiving Macintosh.
  153. It is proposed that a modified procedure be accepted as a standard, to be
  154. implemented instead of or in addition to the above-described MacTerminal
  155. "Mac-to-Mac" protocol in complying terminal programs. The modified procedure,
  156. which is compatible with standard XMODEM implementations, functions as
  157. follows: The transmitting Macintosh sends the two characters ESCAPE (hex 1B)
  158. and "b" (hex 62). The receiving Macintosh may optionally reply with ACK (hex
  159. 06) (this is allowed so as to have minimum impact on existing
  160. MacTerminal-compatible implementations). The transmitting Macintosh then
  161. awaits receipt of a NAK (hex 15) (or optionally a "C" (hex 43), if the
  162. receiving terminal program supports CRC checking), following which a single,
  163. normal XMODEM transfer occurs. The transfer may be in text mode or document
  164. mode, will begin with block number one, and block numbers will increment
  165. uniformly (modulo 256) throughout the transfer.
  166. It is expected that a patch to MacTerminal making it compatible with the above
  167. proposed procedure will be available in the near future.
  168. Responses to proposals:
  169. -----------------------
  170. Please address comments or questions on the above proposals to:
  171.         Dennis F. Brothers
  172.         197 Old Connecticut Path
  173.         Wayland, MA 01778
  174.         617-358-2863
  175.         CompuServe: 70065,172
  176.         Delphi:     DBROTHERS
  177.         MCI Mail:   DBROTHERS
  178. MacBinary Working Group:
  179. ------------------------
  180. An informal working group, consisting of Macintosh terminal program developers
  181. and others with interests or expertise in the field of computer communications,
  182. was formed during April, 1985 to discuss and refine this proposal. The group
  183. met in the MAUG (Micro-networked Apple User's Group) Special Interest Group on
  184. the CompuServe Information Service. The present form of the MacBinary format
  185. standard represents a consensus of this group as a whole, but may not reflect
  186. the opinion of a given individual member of the group.
  187. The working group included:
  188.    Christopher Allen
  189.    William Bond
  190.    Steve Brecher
  191.    Dennis Brothers
  192.    Ward Christensen
  193.    Dan Cochran
  194.    Mike Cohen
  195.    Bill Cook
  196.    Ed Edell
  197.    Duane Harris
  198.    Yves Lempereur
  199.    Neil Shapiro
  200.    Dan Smith
  201.    Bill Steinberg
  202.    Scott Watson
  203.